

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Contributing &mdash; Singularity container 3.5 documentation</title>
  

  
  
    <link rel="shortcut icon" href="_static/favicon.png"/>
  
  
  

  
  <script type="text/javascript" src="_static/js/modernizr.min.js"></script>
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
        <script src="_static/jquery.js"></script>
        <script src="_static/underscore.js"></script>
        <script src="_static/doctools.js"></script>
        <script src="_static/language_data.js"></script>
        <script src="_static/js/ga.js"></script>
    
    <script type="text/javascript" src="_static/js/theme.js"></script>

    

  
  <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  <link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Appendix" href="appendix.html" />
    <link rel="prev" title="GPU (NVIDIA CUDA &amp; AMD ROCm)" href="gpu.html" /> 
</head>

<body class="wy-body-for-nav">

   
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >
          

          
            <a href="index.html" class="icon icon-home"> Singularity container
          

          
            
            <img src="_static/logo.png" class="logo" alt="Logo"/>
          
          </a>

          
            
            
              <div class="version">
                3.5
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul>
<li class="toctree-l1"><a class="reference internal" href="introduction.html">介绍</a></li>
<li class="toctree-l1"><a class="reference internal" href="quick_start.html">快速入门</a></li>
<li class="toctree-l1"><a class="reference internal" href="security.html">Singularity安全</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="build_a_container.html">Build容器</a></li>
<li class="toctree-l1"><a class="reference internal" href="definition_files.html">Definition文件</a></li>
<li class="toctree-l1"><a class="reference internal" href="build_env.html">Build环境</a></li>
<li class="toctree-l1"><a class="reference internal" href="singularity_and_docker.html">Singularity和Docker</a></li>
<li class="toctree-l1"><a class="reference internal" href="fakeroot.html">Fakeroot</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="signNverify.html">签名和认证</a></li>
<li class="toctree-l1"><a class="reference internal" href="key_commands.html">Key管理</a></li>
<li class="toctree-l1"><a class="reference internal" href="encryption.html">容器加密</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="endpoint.html">容器仓库</a></li>
<li class="toctree-l1"><a class="reference internal" href="cloud_library.html">Cloud Library</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="bind_paths_and_mounts.html">路径映射</a></li>
<li class="toctree-l1"><a class="reference internal" href="persistent_overlays.html">持久化Overlay</a></li>
<li class="toctree-l1"><a class="reference internal" href="running_services.html">运行服务</a></li>
<li class="toctree-l1"><a class="reference internal" href="environment_and_metadata.html">环境变量和元数据</a></li>
<li class="toctree-l1"><a class="reference internal" href="oci_runtime.html">OCI运行时</a></li>
<li class="toctree-l1"><a class="reference internal" href="plugins.html">插件</a></li>
<li class="toctree-l1"><a class="reference internal" href="security_options.html">安全选项</a></li>
<li class="toctree-l1"><a class="reference internal" href="networking.html">网络选项</a></li>
<li class="toctree-l1"><a class="reference internal" href="cgroups.html">Cgroups</a></li>
<li class="toctree-l1"><a class="reference internal" href="mpi.html">MPI应用</a></li>
<li class="toctree-l1"><a class="reference internal" href="gpu.html">GPU支持</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Contributing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#join-the-community">Join the community</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#singularity-google-group">Singularity Google Group</a></li>
<li class="toctree-l3"><a class="reference internal" href="#singularity-on-slack">Singularity on Slack</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#raise-an-issue">Raise an Issue</a></li>
<li class="toctree-l2"><a class="reference internal" href="#write-documentation">Write Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#contribute-to-the-code">Contribute to the code</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#step-1-fork-the-repo">Step 1. Fork the repo</a></li>
<li class="toctree-l3"><a class="reference internal" href="#step-2-checkout-a-new-branch">Step 2. Checkout a new branch</a></li>
<li class="toctree-l3"><a class="reference internal" href="#step-3-make-your-changes">Step 3. Make your changes</a></li>
<li class="toctree-l3"><a class="reference internal" href="#step-4-push-your-branch-to-your-fork">Step 4. Push your branch to your fork</a></li>
<li class="toctree-l3"><a class="reference internal" href="#step-5-submit-a-pull-request">Step 5. Submit a Pull Request</a></li>
<li class="toctree-l3"><a class="reference internal" href="#step-6-keep-your-branch-in-sync">Step 6. Keep your branch in sync</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="appendix.html">Appendix</a></li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">Command Line Reference</a></li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">Singularity container</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content style-external-links">
        
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="index.html">Docs</a> &raquo;</li>
        
      <li>Contributing</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            
              <a href="https://github.com/sylabs/singularity-userdocs/blob/master/contributing.rst" class="fa fa-github"> Edit on GitHub</a>
            
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="contributing">
<span id="id1"></span><h1>Contributing<a class="headerlink" href="#contributing" title="Permalink to this headline">¶</a></h1>
<p>Singularity is an open source project, meaning we have the challenge of limited
resources. We are grateful for any support that you can offer. Helping other
users, raising issues, helping write documentation, or contributing code are all
ways to help!</p>
<div class="section" id="join-the-community">
<h2>Join the community<a class="headerlink" href="#join-the-community" title="Permalink to this headline">¶</a></h2>
<p>This is a huge endeavor, and your help would be greatly appreciated! Post to
online communities about Singularity, and request that your distribution vendor,
service provider, and system administrators include Singularity for you!</p>
<div class="section" id="singularity-google-group">
<h3>Singularity Google Group<a class="headerlink" href="#singularity-google-group" title="Permalink to this headline">¶</a></h3>
<p>If you have been using Singularity and having good luck with it, join our
<a class="reference external" href="https://groups.google.com/a/lbl.gov/forum/#!forum/singularity">Google Group</a>  and help out
other users!</p>
</div>
<div class="section" id="singularity-on-slack">
<h3>Singularity on Slack<a class="headerlink" href="#singularity-on-slack" title="Permalink to this headline">¶</a></h3>
<p>Many of our users come to Slack for quick help with an issue. You can find us at
<a class="reference external" href="https://singularity-container.slack.com/">singularity-container</a>.</p>
</div>
</div>
<div class="section" id="raise-an-issue">
<span id="report-a-issue"></span><span id="contributing-to-documentation"></span><h2>Raise an Issue<a class="headerlink" href="#raise-an-issue" title="Permalink to this headline">¶</a></h2>
<p>For general bugs/issues, you can open an issue <a class="reference external" href="https://github.com/sylabs/singularity/issues/new">at the GitHub repo</a>. However, if you find a
security  related issue/problem, please email Sylabs directly at
<a class="reference external" href="mailto:security&#37;&#52;&#48;sylabs&#46;io">security<span>&#64;</span>sylabs<span>&#46;</span>io</a>. More information about the
Sylabs security policies and procedures can be found <a class="reference external" href="https://www.sylabs.io/singularity/security-policy/">here</a></p>
</div>
<div class="section" id="write-documentation">
<h2>Write Documentation<a class="headerlink" href="#write-documentation" title="Permalink to this headline">¶</a></h2>
<p>We (like almost all open source software providers) have a documentation
dilemma… We tend to focus on the code features and functionality before working
on documentation. And there is very good reason for this: we want to share the
love so nobody feels left out!</p>
<p>You can contribute to the documentation by <a class="reference external" href="https://github.com/sylabs/singularity-userdocs/issues/new">raising an issue to suggest an
improvement</a> or by
sending a <a class="reference external" href="https://github.com/sylabs/singularity-userdocs/compare">pull request</a> on <a class="reference external" href="https://github.com/sylabs/singularity-userdocs">our repository
for documentation</a>.</p>
<p>The current documentation is generated with:</p>
<ul class="simple">
<li><p><a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructured Text (RST)</a> and <a class="reference external" href="https://readthedocs.org/">ReadTheDocs</a>.</p></li>
</ul>
<p>Other dependencies include:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.python.org/download/releases/2.7/">Python 2.7</a>.</p></li>
<li><p><a class="reference external" href="https://pypi.org/project/Sphinx/">Sphinx</a>.</p></li>
</ul>
<p>More information about contributing to the documentation, instructions on how to
install the dependencies, and how to generate the files can be obtained
<a class="reference external" href="https://github.com/sylabs/singularity-userdocs/blob/master/README.md#singularity-user-docs">here</a>.</p>
<p>For more information on using Git and GitHub to create a pull request suggesting
additions and edits to the docs, see the <a class="reference internal" href="#contribute-to-the-code"><span class="std std-ref">section on contributing to the
code</span></a>. The procedure is identical for contributions to
the documentation and the code base.</p>
</div>
<div class="section" id="contribute-to-the-code">
<span id="id2"></span><h2>Contribute to the code<a class="headerlink" href="#contribute-to-the-code" title="Permalink to this headline">¶</a></h2>
<p>We use the traditional
<a class="reference external" href="https://guides.github.com/introduction/flow/">GitHub Flow</a> to develop. This
means that you fork the main repo, create a new branch to make changes, and
submit a pull request (PR) to the master branch.</p>
<p>Check out our official <a class="reference external" href="https://github.com/sylabs/singularity/blob/master/CONTRIBUTING.md">CONTRIBUTING.md</a> document,
which also includes a <a class="reference external" href="https://github.com/sylabs/singularity/blob/master/CONTRIBUTING.md#code-of-conduct">code of conduct</a>.</p>
<div class="section" id="step-1-fork-the-repo">
<h3>Step 1. Fork the repo<a class="headerlink" href="#step-1-fork-the-repo" title="Permalink to this headline">¶</a></h3>
<p>To contribute to Singularity, you should obtain a GitHub account and fork the
<a class="reference external" href="https://github.com/sylabs/singularity">Singularity</a> repository. Once forked,
clone your fork of the repo to your computer. (Obviously, you should replace
<code class="docutils literal notranslate"><span class="pre">your-username</span></code> with your GitHub username.)</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ git clone https://github.com/your-username/singularity.git &amp;&amp; \
    cd singularity/
</pre></div>
</div>
</div>
<div class="section" id="step-2-checkout-a-new-branch">
<h3>Step 2. Checkout a new branch<a class="headerlink" href="#step-2-checkout-a-new-branch" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="https://guides.github.com/introduction/flow//">Branches</a> are a way of
isolating your features from the main branch. Given that we’ve just cloned the
repo, we will probably want to make a new branch from master in which to work on
our new feature. Lets call that branch <code class="docutils literal notranslate"><span class="pre">new-feature</span></code>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ git checkout master &amp;&amp; \
    git checkout -b new-feature
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You can always check which branch you are in by running <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">branch</span></code>.</p>
</div>
</div>
<div class="section" id="step-3-make-your-changes">
<h3>Step 3. Make your changes<a class="headerlink" href="#step-3-make-your-changes" title="Permalink to this headline">¶</a></h3>
<p>On your new branch, go nuts! Make changes, test them, and when you are happy
commit the changes to the branch:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ git add file-changed1 file-changed2...

$ git commit -m &quot;what changed?&quot;
</pre></div>
</div>
<p>This commit message is important - it should describe exactly the changes that
you have made. Good commit messages read like so:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ git commit -m &quot;changed function getConfig in functions.go to output csv to fix #2&quot;

$ git commit -m &quot;updated docs about shell to close #10&quot;
</pre></div>
</div>
<p>The tags <code class="docutils literal notranslate"><span class="pre">close</span> <span class="pre">#10</span></code> and <code class="docutils literal notranslate"><span class="pre">fix</span> <span class="pre">#2</span></code> are referencing issues that are posted on
the upstream repo where you will direct your pull request. When your PR is
merged into the master branch, these messages will automatically close the
issues, and further, they will link your commits directly to the issues they
intend to fix. This will help future maintainers understand your contribution,
or (hopefully not) revert the code back to a previous version if necessary.</p>
</div>
<div class="section" id="step-4-push-your-branch-to-your-fork">
<h3>Step 4. Push your branch to your fork<a class="headerlink" href="#step-4-push-your-branch-to-your-fork" title="Permalink to this headline">¶</a></h3>
<p>When you are done with your commits, you should push your branch to your fork
(and you can also continuously push commits here as you work):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ git push origin new-feature
</pre></div>
</div>
<p>Note that you should always check the status of your branches to see what has
been pushed (or not):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ git status
</pre></div>
</div>
</div>
<div class="section" id="step-5-submit-a-pull-request">
<h3>Step 5. Submit a Pull Request<a class="headerlink" href="#step-5-submit-a-pull-request" title="Permalink to this headline">¶</a></h3>
<p>Once you have pushed your branch, then you can go to your fork (in the web GUI
on GitHub) and <a class="reference external" href="https://help.github.com/articles/creating-a-pull-request/">submit a Pull Request</a>. Regardless of the
name of your branch, your PR should be submitted to the Sylabs <code class="docutils literal notranslate"><span class="pre">master</span></code>
branch. Submitting your PR will open a conversation thread for the maintainers
of Singularity to discuss your contribution. At this time, the continuous
integration that is linked with the code base will also be executed. If there is
an issue, or if the maintainers suggest changes, you can continue to push
commits to your branch and they will update the Pull Request.</p>
</div>
<div class="section" id="step-6-keep-your-branch-in-sync">
<h3>Step 6. Keep your branch in sync<a class="headerlink" href="#step-6-keep-your-branch-in-sync" title="Permalink to this headline">¶</a></h3>
<p>Cloning the repo will create an exact copy of the Singularity repository at that
moment. As you work, your branch may become out of date as others merge changes
into the upstream master. In the event that you need to update a branch, you
will need to follow the next steps:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ git remote add upstream https://github.com/sylabs/singularity.git &amp;&amp; # to add a new remote named &quot;upstream&quot; \
    git checkout master &amp;&amp; # or another branch to be updated \
    git pull upstream master &amp;&amp; \
    git push origin master &amp;&amp; # to update your fork \
    git checkout new-feature &amp;&amp; \
    git merge master
</pre></div>
</div>
</div>
</div>
</div>


           </div>
           
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="appendix.html" class="btn btn-neutral float-right" title="Appendix" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="gpu.html" class="btn btn-neutral float-left" title="GPU (NVIDIA CUDA &amp; AMD ROCm)" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2017-2019, Sylabs Inc

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>